<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.4.5" />
<title>libmodbus(7)</title>
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock {
  padding-left: 2.0em;
  margin-right: 10%;
}
div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock {
  padding-left: 2.0em;
  margin-right: 10%;
}
div.verseblock > div.content {
  white-space: pre;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
}

div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

@media print {
  div#footer-badges { display: none; }
}

div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
/* Overrides for manpage documents */
h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
h2 {
  border-style: none;
}
div.sectionbody {
  margin-left: 5%;
}

@media print {
  div#toc { display: none; }
}

/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock-content {
  white-space: pre;
}
div.verseblock-attribution {
  padding-top: 0.75em;
  text-align: left;
}

div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
</head>
<body>
<div id="header">
<h1>
libmodbus(7) Manual Page
</h1>
<h2>NAME</h2>
<div class="sectionbody">
<p>libmodbus -
   a fast and portable Modbus library
</p>
</div>
</div>
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="paragraph"><p><strong>#include &lt;modbus.h&gt;</strong></p></div>
<div class="paragraph"><p><strong>cc</strong> `pkg-config --cflags --libs libmodbus` <em>files</em></p></div>
</div>
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph"><p>libmodbus is a library to send/receive data with a device which respects the
Modbus protocol. This library contains various backends to communicate over
different networks (eg. serial in RTU mode or Ethernet in TCP/IPv6). The
<a href="http://www.modbus.org">http://www.modbus.org</a> site provides documentation about the protocol at
<a href="http://www.modbus.org/specs.php">http://www.modbus.org/specs.php</a>.</p></div>
<div class="paragraph"><p>libmodbus provides an abstraction of the lower communication layers and offers
the same API on all supported platforms.</p></div>
<div class="paragraph"><p>This documentation presents an overview of libmodbus concepts, describes how
libmodbus abstracts Modbus communication with different hardware and platforms
and provides a reference manual for the functions provided by the libmodbus
library.</p></div>
<h3 id="_contexts">Contexts</h3><div style="clear:left"></div>
<div class="paragraph"><p>The Modbus protocol contains many variants (eg. serial RTU or Ehternet TCP), to
ease the implementation of a variant, the library was designed to use a backend
for each variant. The backends are also a convenient way to fulfill other
requirements (eg. real-time operations). Each backend offers a specific function
to create a new <em>modbus_t</em> context. The <em>modbus_t</em> context is an opaque
structure containing all necessary information to establish a connection with
others Modbus devices according to the selected variant.</p></div>
<div class="paragraph"><p>You can choose the best context for your needs among:</p></div>
<h4 id="_rtu_context">RTU Context</h4>
<div class="paragraph"><p>The RTU backend (Remote Terminal Unit) is used in serial communication and makes
use of a compact, binary representation of the data for protocol
communication. The RTU format follows the commands/data with a cyclic redundancy
check checksum as an error check mechanism to ensure the reliability of
data. Modbus RTU is the most common implementation available for Modbus. A
Modbus RTU message must be transmitted continuously without inter-character
hesitations (extract from Wikipedia, Modbus, <a href="http://en.wikipedia.org/wiki/Modbus">http://en.wikipedia.org/wiki/Modbus</a>
(as of Mar. 13, 2011, 20:51 GMT).</p></div>
<div class="paragraph"><p>The Modbus RTU framing calls a slave, a device/service which handle Modbus
requests, and a master, a client which send requests. The communication is
always initiated by the master.</p></div>
<div class="paragraph"><p>Many Modbus devices can be connected together on the same physical link so you
need to define which slave is concerned by the message with
<a href="modbus_set_slave.html">modbus_set_slave(3)</a>. If you&#8217;re running a slave, the slave number
is used to filter messages.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Create a Modbus RTU context
</dt>
<dd>
<p>
    <a href="modbus_new_rtu.html">modbus_new_rtu(3)</a>
</p>
</dd>
<dt class="hdlist1">
Set the serial mode
</dt>
<dd>
<p>
    <a href="modbus_rtu_get_serial_mode.html">modbus_rtu_get_serial_mode(3)</a>
    <a href="modbus_rtu_set_serial_mode.html">modbus_rtu_set_serial_mode(3)</a>
</p>
</dd>
</dl></div>
<h4 id="_tcp_ipv4_context">TCP (IPv4) Context</h4>
<div class="paragraph"><p>The TCP backend implements a Modbus variant used for communications over
TCP/IPv4 networks. It does not require a checksum calculation as lower layer
takes care of the same.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Create a Modbus TCP context
</dt>
<dd>
<p>
    <a href="modbus_new_tcp.html">modbus_new_tcp(3)</a>
</p>
</dd>
</dl></div>
<h4 id="_tcp_pi_ipv4_and_ipv6_context">TCP PI (IPv4 and IPv6) Context</h4>
<div class="paragraph"><p>The TCP PI (Protocol Indepedent) backend implements a Modbus variant used for
communications over TCP IPv4 and IPv6 networks. It does not require a checksum
calculation as lower layer takes care of the same.</p></div>
<div class="paragraph"><p>Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname
resolution but it consumes about 1Kb of additional memory.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Create a Modbus TCP context
</dt>
<dd>
<p>
    <a href="modbus_new_tcp_pi.html">modbus_new_tcp_pi(3)</a>
</p>
</dd>
</dl></div>
<h4 id="_common">Common</h4>
<div class="paragraph"><p>Before using any libmodbus functions, the caller must allocate and initialize a
<em>modbus_t</em> context with functions explained above, then the following functions
are provided to modify and free a <em>context</em>:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Free libmodbus context
</dt>
<dd>
<p>
    <a href="modbus_free.html">modbus_free(3)</a>
</p>
</dd>
<dt class="hdlist1">
Context setters and getters
</dt>
<dd>
<p>
    <a href="modbus_get_byte_timeout.html">modbus_get_byte_timeout(3)</a>
    <a href="modbus_set_byte_timeout.html">modbus_set_byte_timeout(3)</a>
    <a href="modbus_set_debug.html">modbus_set_debug(3)</a>
    <a href="modbus_set_error_recovery.html">modbus_set_error_recovery(3)</a>
    <a href="modbus_get_header_length.html">modbus_get_header_length(3)</a>
    <a href="modbus_get_response_timeout.html">modbus_get_response_timeout(3)</a>
    <a href="modbus_set_response_timeout.html">modbus_set_response_timeout(3)</a>
    <a href="modbus_set_slave.html">modbus_set_slave(3)</a>
    <a href="modbus_set_socket.html">modbus_set_socket(3)</a>
    <a href="modbus_get_socket.html">modbus_get_socket(3)</a>
</p>
</dd>
</dl></div>
<div class="paragraph"><p>A libmodbus <em>context</em> is thread safe and may be shared among as many application
threads as necessary, without any additional locking required on the part of the
caller.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Macros for data manipulation
</dt>
<dd>
<p>
    MODBUS_GET_HIGH_BYTE(data), extracts the high byte from a byte
    MODBUS_GET_LOW_BYTE(data), extracts the low byte from a byte
    MODBUS_GET_INT32_FROM_INT16(tab_int16, index), builds an int32 from the two
    first int16 starting at tab_int16[index]
    MODBUS_GET_INT16_FROM_INT8(tab_int8, index), builds an int16 from the two
    first int8 starting at tab_int8[index]
    MODBUS_SET_INT16_TO_INT8(tab_int8, index, value), set an int16 value into
    the two first bytes starting at tab_int8[index]
</p>
</dd>
<dt class="hdlist1">
Functions for data manipulation
</dt>
<dd>
<p>
    <a href="modbus_set_bits_from_byte.html">modbus_set_bits_from_byte(3)</a>
    <a href="modbus_set_bits_from_bytes.html">modbus_set_bits_from_bytes(3)</a>
    <a href="modbus_get_byte_from_bits.html">modbus_get_byte_from_bits(3)</a>
    <a href="modbus_get_float.html">modbus_get_float(3)</a>
    <a href="modbus_set_float.html">modbus_set_float(3)</a>
</p>
</dd>
</dl></div>
<h3 id="_connection">Connection</h3><div style="clear:left"></div>
<div class="paragraph"><p>The following functions are provided to establish and close a connection with
Modbus devices:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Establish a connection
</dt>
<dd>
<p>
    <a href="modbus_connect.html">modbus_connect(3)</a>
</p>
</dd>
<dt class="hdlist1">
Close a connection
</dt>
<dd>
<p>
    <a href="modbus_close.html">modbus_close(3)</a>
</p>
</dd>
<dt class="hdlist1">
Flush a connection
</dt>
<dd>
<p>
    <a href="modbus_flush.html">modbus_flush(3)</a>
</p>
</dd>
</dl></div>
<h3 id="_client">Client</h3><div style="clear:left"></div>
<div class="paragraph"><p>The Modbus protocol defines different data types and functions to read and write
them from/to remote devices. The following functions are used by the clients to
send Modbus requests:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Read data
</dt>
<dd>
<p>
     <a href="modbus_read_bits.html">modbus_read_bits(3)</a>
     <a href="modbus_read_input_bits.html">modbus_read_input_bits(3)</a>
     <a href="modbus_read_registers.html">modbus_read_registers(3)</a>
     <a href="modbus_read_input_registers.html">modbus_read_input_registers(3)</a>
     <a href="modbus_report_slave_id.html">modbus_report_slave_id(3)</a>
</p>
</dd>
<dt class="hdlist1">
Write data
</dt>
<dd>
<p>
     <a href="modbus_write_bit.html">modbus_write_bit(3)</a>
     <a href="modbus_write_register.html">modbus_write_register(3)</a>
     <a href="modbus_write_bits.html">modbus_write_bits(3)</a>
     <a href="modbus_write_registers.html">modbus_write_registers(3)</a>
</p>
</dd>
<dt class="hdlist1">
Write and read data
</dt>
<dd>
<p>
      <a href="modbus_write_and_read_registers.html">modbus_write_and_read_registers(3)</a>
</p>
</dd>
<dt class="hdlist1">
Raw requests
</dt>
<dd>
<p>
    <a href="modbus_send_raw_request.html">modbus_send_raw_request(3)</a>
    <a href="modbus_receive_confirmation.html">modbus_receive_confirmation(3)</a>
</p>
</dd>
<dt class="hdlist1">
Reply an exception
</dt>
<dd>
<p>
    <a href="modbus_reply_exception.html">modbus_reply_exception(3)</a>
</p>
</dd>
</dl></div>
<h3 id="_server">Server</h3><div style="clear:left"></div>
<div class="paragraph"><p>The server is waiting for request from clients and must answer when it is
concerned by the request. The libmodbus offers the following functions to
handle requests:</p></div>
<div class="paragraph"><p>Data mapping:
     <a href="modbus_mapping_new.html">modbus_mapping_new(3)</a>
     <a href="modbus_mapping_free.html">modbus_mapping_free(3)</a></p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
Receive
</dt>
<dd>
<p>
     <a href="modbus_receive.html">modbus_receive(3)</a>
</p>
</dd>
<dt class="hdlist1">
Reply
</dt>
<dd>
<p>
     <a href="modbus_reply.html">modbus_reply(3)</a>
     <a href="modbus_reply_exception.html">modbus_reply_exception(3)</a>
</p>
</dd>
</dl></div>
</div>
<h2 id="_error_handling">ERROR HANDLING</h2>
<div class="sectionbody">
<div class="paragraph"><p>The libmodbus functions handle errors using the standard conventions found on
POSIX systems. Generally, this means that upon failure a libmodbus function
shall return either a NULL value (if returning a pointer) or a negative value
(if returning an integer), and the actual error code shall be stored in the
<em>errno</em> variable.</p></div>
<div class="paragraph"><p>The <em>modbus_strerror()</em> function is provided to translate libmodbus-specific
error codes into error message strings; for details refer to
<a href="modbus_strerror.html">modbus_strerror(3)</a>.</p></div>
</div>
<h2 id="_miscellaneous">MISCELLANEOUS</h2>
<div class="sectionbody">
<div class="paragraph"><p>The <em>LIBMODBUS_VERSION_STRING</em> constant indicates the libmodbus version the
program has been compiled against. The variables <em>libmodbus_version_major</em>,
<em>libmodbus_version_minor</em>, <em>libmodbus_version_micro</em> give the version the
program is linked against.</p></div>
</div>
<h2 id="_authors">AUTHORS</h2>
<div class="sectionbody">
<div class="paragraph"><p>The libmodbus documentation was written by Stéphane Raimbault
&lt;<a href="mailto:stephane.raimbault@gmail.com">stephane.raimbault@gmail.com</a>&gt;</p></div>
</div>
<h2 id="_resources">RESOURCES</h2>
<div class="sectionbody">
<div class="paragraph"><p>Main web site: <a href="http://www.libmodbus.org/">http://www.libmodbus.org/</a></p></div>
<div class="paragraph"><p>Report bugs on the issue tracker at
<a href="http://github.com/stephane/libmodbus/issues">http://github.com/stephane/libmodbus/issues</a>.</p></div>
</div>
<h2 id="_copying">COPYING</h2>
<div class="sectionbody">
<div class="paragraph"><p>Free use of this software is granted under the terms of the GNU Lesser General
Public License (LGPL v2.1+). For details see the files <tt>COPYING</tt> and
<tt>COPYING.LESSER</tt> included with the libmodbus distribution.</p></div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
libmodbus 3.0.5<br />
Last updated 2013-10-06 22:29:39 CEST
</div>
</div>
</body>
</html>
